================================================================================
	  	 Matlab mode for Alpha, version 2.0b2
================================================================================

This is a set of TCL proc's that allow the shareware Macintosh text editor 
Alpha to act as a front end for MATLAB for Macintosh version 4.2c or 
higher.  Requires Alpha 7.0fc1 or higher.  While you can work with MATLAB 
4.2c, you should upgrade to MATLAB 5 to avoid the a serious bug in MATLAB 
4.2c as described below.

================================================================================
	  	 Main Features
================================================================================

 Syntax coloring of keywords
 Automatic line indentation
 Shell like command window for typing in MATLAB commands
 Command history window for easy reissuing of commands
 "Save and Go" for executing m-files
 Execute line or selection sends command(s) to MATLAB
 Get help or open files by selecting or Cmd-double clicking commands
 Debug menu for easy use of MATLAB debugging
 Workspace menu for easy management of the MATLAB workspace
 Can automatically clear old function from workspace when saving file
 Utility to create HTML documentation of MATLAB files

================================================================================
	  	 WARNING
================================================================================

There is a bug in MATLAB 4.2c that will cause MATLAB to crash if the return 
string from a dosc apple event is large.  Since MATLAB mode uses the dosc 
event to talk to MATLAB you should not execute MATLAB scripts from Alpha 
(or Apple Scripts for that matter) that will print large results to the 
screen.  So, for example, don't do this

 1:1000

As far as I know there is nothing I can do to prevent this from happening.  

This bug has been fixed in MATLAB 5.

================================================================================
	  	 Usage
================================================================================

	  	   Editing matlab files

If you open any text file with a .m extension, Alpha will automatically 
recognize it as a MATLAB file and set the current mode to be MATL.  You 
type in your MATLAB code as you normally would, but matlabMode helps you in 
several ways.  It will color certain key words.  You can easily change the 
coloring scheme by setting the mode flags from the 
"Config:Current Mode:Preferences..." menu.

As you type you may notice some strange behavior.  If you hit return, the 
next line will be automatically indented for you according to the previous 
lines indentation and the block structure.  You can turn off this feature 
by unselecting "electricReturn" in the mode flags.  In addition if you type 
a semicolon ";", matlabMode will automatically hit return for you.  You can 
turn off this feature by unselecting "electricSemi" in the mode flags.

Once you are finished editing the MATLAB file you can select 
"saveAndExecute" from the MATLAB menu to send the file to MATLAB for 
execution.  The results will be shown in the command window within Alpha.  
If you only want to execute part of the file simply select the code you 
want and then choose executeSelection from the MATLAB menu.

If there is a matlab file in your code that you wish to edit you can easily 
open several ways.  One is to select the name and the choose 
"openSelection" from the MATLAB menu.  Another way is to Hold down the cmd 
(splat, apple,...) key and double click on the matlab command.  This will 
bring up help on that command.  Hold down both the cmd and control keys and 
double click to edit the m-files.  The mode variable DblClickEdits (settable 
from the Config:Current Mode:Preferences..." menu) will reverse this behavior.


	  	   Command window

This acts similar to the command window in MATLAB.  Simply type in a 
command at the prompt and hit return to have it executed in MATLAB.  Use 
the up and down arrow keys to recall previous commands.  Hit control-u to 
cancel the current line.


	  	   Command history window

This acts similar to the history window in MATLAB: it contains a list of 
all previous commands entered in the command window.  Commands sent from 
m-files are not added.  Use the arrow keys to navigate up or down and hit 
return to reissue the command.


	  	   Cmd-Double Clicking

Hold down the cmd (splat, apple,...) key and double click on a matlab 
command.  This will bring up help on that command.  Hold down both the cmd 
and control keys and double click to edit the m-files depending.  The mode 
variable DblClickEdits (settable from Config:Current Mode:Preferences..." 
or the "Quick Options" menu) will reverse this behavior.

	  	   Menu Items
			
	  	     Matlab Menu

switchToMatlab       Swap the process to matlab, launching if necessary

commandWindow        Open command window

commandHistory       Open history window

editInMatlab         Close and edit current window in Matlab

executeSelection     Execute selection in Matlab; if nothing is selected
                     execute current line

saveAndExecute       Save and execute current window

openSelection        Open m-files of selection


	  	     Command Help Menu

normalHelp           Presents a dialog box for entering in a command to ask
                     MATLAB for help on.
							
helpSelection        Get help on selected command in current window

searchDocumentation  Search for help on a keyword

makeDocumentation    Create HTML documentation for a folder of m-files


	  	     Workspace Menu

rebuildPath          Sends a "path(path)" to MATLAB

addToPath            Get the path of current window and add it to MATLAB's path

cdToWin              Set current directory to the folder of the current window

clearWorkspace       Sends a "clear" to MATLAB

clearProcedure       Removes current window's function from the workspace
                     ("clear m-file").
							
closeAll             Closes all MATLAB figure windows ("close all")						

	  	     Debug Menu

stopIfError          Sends "dbstop if error" to MATLAB

stopInFile           Sends "dbstop in m-file" to MATLAB

stopAtCurrentLine    Sends  "dbstop at current-line in m-file" to MATLAB

stepOneLine          Sends "dbstep 1" to MATLAB

clearAllBreakpoints  Sends "dbclear all" to MATLAB

fileBreakpoints      Sends "dbstatus m-file" to MATLAB

openErrorFile        Opens the offending file if an error occurred on the 
                     last command.

	  	     Quick Options Menu
			
clearOnSave          If selected sends a "clear functionName" to MATLAB when
                     saving a file.  Useful when the function is a callback and 
							MATLAB doesn't check if it has changed.
							
webHelp              All help commands open up the HTML help file if available


							
	  	   Non-Menu Key Bindings

*All windows*

opt-;       Electric semicolon with jump to next stop

*Command Window Only*

return       Execute current command line in Matlab
up arrow     Recall Previous Command
down arrow   Recall Next Command
control-u    Cancel Line

*m-files Window Only*

control-return  Execute current line in Matlab


================================================================================
	  	 Customization
================================================================================

Here are some things you can set from the "Config:Current Mode:Preferences..." 
menu:

   1. Change the name of the command window
   2. Change the name command history window
   3. Toggle the behavior of Cmd-Double Clicking.
   4. Set the color of the different kinds of keywords.
   5. Turn off electric semicolon
   6. Turn off auto-indentation (elecReturn)
	7. Turn off warning that Matlab is busy (queEventsQuietly)
	8. Use web browser to view help files or use normal Matlab help
	9. Automatically send a clear function command to Matlab when saving a file
   
In addition if you want to add menu items you can define a proc in Tcl called
matDummyMenuItem and then simply add items to the matlab menu without 
having to modify matlabMode.tcl.   For example:

	addMenuItem $MATLMenu 	"(-"
	addMenuItem $MATLMenu  "stephen"
	
	proc matDummyMenuItem {menu item} {
		global MATLMenu
		switch $menu $MATLMenu {
			switch $item {
				stephen   {insertText "Smart guy"}
			}
		}
	}

 
================================================================================
	  	 Version History
================================================================================

	  	   Changes in Version 2.0b2

 Added a queue of events sent to Matlab
 Removed waitForResults as events are now queued

	  	   Changes in Version 2.0b1

 Made compatible with Alpha 7.0b2
 Removed Electric Alias Support (no longer in Alpha)
 Broke source into many files
 Added makeDocumentation to make HTML docs from m-files

	  	   Changes in Version 1.4

 Added MATLMarkFile
 Added auto-indentation
 Electric Alias Support
 Electric Semicolon
 Added MATLAB HTML help
 Added option to clear function on save
 Added option to not wait for results

	  	   Changes in Version 1.3

 Changed mode installation for Alpha 6.2b6 Tcl reorganization.
 Created command history window.
 Renamed more procedures to be more consistent.
 Created mode variables for special window names.
 Added openErrorFile

	  	   Changes in Version 1.2

 Added control option to DblClickEdits (Requires Alpha 6.04)
 MATLMenu  "405" now an Alpha resource
 Got rid of MATc mode
 Added matHelp
 Turned on shell flag of command window
 Added matDummyMenuItem proc so users can add items easily to MATLMenu
 Added workspace and debug submenus
 Created matlabMode.tcl so tclIndexes can be used

	  	   Changes in Version 1.1

 Added cmd-double clicking code by Tom Pollard
 cleaned up prompting in command window
 Removed "redundant" do's from menu
 Open selection now opens associated m-files if selection is a .mex
 Fixed up command line recall

	  	   Changes in Version 1.0.1

 Fixed a bug in matlabCarriageReturn

	  	   Changes in Version 1.0

 Added openSelection
 Added command line recall in command window
 Fixed doLine
 Changed key bindings and put some in menu


================================================================================
	  	 To Do:
================================================================================

 Insert comment above command line for dbstep in command window
 Add check for error from MATLAB on debugging procs
 Workspace list window
 Help Browser
 "Word completion" in command window
 Loop thru lines in multi-line sends
  
================================================================================
	  	 Signature
================================================================================

This mode was written by Stephen Merkowitz.  Some code was stolen from 
other TCL files distributed with Alpha (mostly shell.tcl).  Thanks to Tom 
Pollard who gave me cmd-double clicking code along with other fixes.  
Comments, suggestions, and bug reports should be sent to Stephen at
<Stephen.Merkowitz@lnf.infn.it>.

You should be able to find the most recent version of MATLAB mode at 
<http://phwave.phys.lsu.edu/~merkowitz/alpha/>

If you would like to be notified of new releases of MATLAB mode send mail 
to Stephen at <Stephen.Merkowitz@lnf.infn.it>.
